<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Suggesters | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'search-suggesters.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/search-suggesters.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/search-suggesters.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/search-suggesters.html" rel="nofollow" target="_blank">../en/search-suggesters.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="search.html">Search APIs</a></span>
»
<span class="breadcrumb-node">Suggesters</span>
</div>
<div class="navheader">
<span class="prev">
<a href="search-shards.html">« Search Shards API</a>
</span>
<span class="next">
<a href="search-multi-search.html">Multi Search API »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="search-suggesters"></a>Suggesters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters.asciidoc">edit</a>
</h2>
</div></div></div>
<p>Suggests similar looking terms based on a provided text by using a suggester.
Parts of the suggest feature are still under development.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST twitter/_search
{
  "query" : {
    "match": {
      "message": "tring out Elasticsearch"
    }
  },
  "suggest" : {
    "my-suggestion" : {
      "text" : "tring out Elasticsearch",
      "term" : {
        "field" : "message"
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2002.console"></div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-suggesters-api-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The suggest feature suggests similar looking terms based on a provided text by
using a suggester. The suggest request part is defined alongside the query part
in a <code class="literal">_search</code> request. If the query part is left out, only suggestions are
returned.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p><code class="literal">_suggest</code> endpoint has been deprecated in favour of using suggest via
<code class="literal">_search</code> endpoint. In 5.0, the <code class="literal">_search</code> endpoint has been optimized for
suggest only search requests.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-suggesters-api-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Several suggestions can be specified per request. Each suggestion is identified
with an arbitrary name. In the example below two suggestions are requested. Both
<code class="literal">my-suggest-1</code> and <code class="literal">my-suggest-2</code> suggestions use the <code class="literal">term</code> suggester, but have
a different <code class="literal">text</code>.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST _search
{
  "suggest": {
    "my-suggest-1" : {
      "text" : "tring out Elasticsearch",
      "term" : {
        "field" : "message"
      }
    },
    "my-suggest-2" : {
      "text" : "kmichy",
      "term" : {
        "field" : "user"
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2003.console"></div>
<p>The below suggest response example includes the suggestion response for
<code class="literal">my-suggest-1</code> and <code class="literal">my-suggest-2</code>. Each suggestion part contains
entries. Each entry is effectively a token from the suggest text and
contains the suggestion entry text, the original start offset and length
in the suggest text and if found an arbitrary number of options.</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "_shards": ...
  "hits": ...
  "took": 2,
  "timed_out": false,
  "suggest": {
    "my-suggest-1": [ {
      "text": "tring",
      "offset": 0,
      "length": 5,
      "options": [ {"text": "trying", "score": 0.8, "freq": 1 } ]
    }, {
      "text": "out",
      "offset": 6,
      "length": 3,
      "options": []
    }, {
      "text": "elasticsearch",
      "offset": 10,
      "length": 13,
      "options": []
    } ],
    "my-suggest-2": ...
  }
}</pre>
</div>
<p>Each options array contains an option object that includes the
suggested text, its document frequency and score compared to the suggest
entry text. The meaning of the score depends on the used suggester. The
term suggester’s score is based on the edit distance.</p>
<h5>
<a id="global-suggest"></a>Global suggest text<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters.asciidoc">edit</a>
</h5>
<p>To avoid repetition of the suggest text, it is possible to define a
global text. In the example below the suggest text is defined globally
and applies to the <code class="literal">my-suggest-1</code> and <code class="literal">my-suggest-2</code> suggestions.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST _search
{
  "suggest": {
    "text" : "tring out Elasticsearch",
    "my-suggest-1" : {
      "term" : {
        "field" : "message"
      }
    },
    "my-suggest-2" : {
       "term" : {
        "field" : "user"
       }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2004.console"></div>
<p>The suggest text can in the above example also be specified as
suggestion specific option. The suggest text specified on suggestion
level override the suggest text on the global level.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="term-suggester"></a>Term suggester<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/term-suggest.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>In order to understand the format of suggestions, please
read the <a class="xref" href="search-suggesters.html" title="Suggesters">Suggesters</a> page first.</p>
</div>
</div>
<p>The <code class="literal">term</code> suggester suggests terms based on edit distance. The provided
suggest text is analyzed before terms are suggested. The suggested terms
are provided per analyzed suggest text token. The <code class="literal">term</code> suggester
doesn’t take the query into account that is part of request.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_common_suggest_options"></a>Common suggest options:<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/term-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">text</code>
</p>
</td>
<td valign="top">
<p>
The suggest text. The suggest text is a required option that
needs to be set globally or per suggestion.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">field</code>
</p>
</td>
<td valign="top">
<p>
The field to fetch the candidate suggestions from. This is
a required option that either needs to be set globally or per
suggestion.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">analyzer</code>
</p>
</td>
<td valign="top">
<p>
The analyzer to analyse the suggest text with. Defaults
to the search analyzer of the suggest field.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">size</code>
</p>
</td>
<td valign="top">
<p>
The maximum corrections to be returned per suggest text
token.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">sort</code>
</p>
</td>
<td valign="top">
<p>
</p>
<p>
Defines how suggestions should be sorted per suggest text
term. Two possible values:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">score</code>:     Sort by score first, then document frequency and
then the term itself.
</li>
<li class="listitem">
<code class="literal">frequency</code>: Sort by document frequency first, then similarity
score and then the term itself.
</li>
</ul>
</div>

</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">suggest_mode</code>
</p>
</td>
<td valign="top">
<p>
</p>
<p>
The suggest mode controls what suggestions are
included or controls for what suggest text terms, suggestions should be
suggested. Three possible values can be specified:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">missing</code>:  Only provide suggestions for suggest text terms that are
not in the index. This is the default.
</li>
<li class="listitem">
<code class="literal">popular</code>:  Only suggest suggestions that occur in more docs than
the original suggest text term.
</li>
<li class="listitem">
<code class="literal">always</code>:   Suggest any matching suggestions based on terms in the
suggest text.
</li>
</ul>
</div>

</td>
</tr>
</tbody>
</table>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_other_term_suggest_options"></a>Other term suggest options:<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/term-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">max_edits</code>
</p>
</td>
<td valign="top">
<p>
The maximum edit distance candidate suggestions can
have in order to be considered as a suggestion. Can only be a value
between 1 and 2. Any other value results in a bad request error being
thrown. Defaults to 2.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">prefix_length</code>
</p>
</td>
<td valign="top">
<p>
The number of minimal prefix characters that must
match in order be a candidate for suggestions. Defaults to 1. Increasing
this number improves spellcheck performance. Usually misspellings don’t
occur in the beginning of terms. (Old name "prefix_len" is deprecated)
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">min_word_length</code>
</p>
</td>
<td valign="top">
<p>
The minimum length a suggest text term must have in
order to be included. Defaults to 4. (Old name "min_word_len" is deprecated)
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">shard_size</code>
</p>
</td>
<td valign="top">
<p>
Sets the maximum number of suggestions to be retrieved
from each individual shard. During the reduce phase only the top N
suggestions are returned based on the <code class="literal">size</code> option. Defaults to the
<code class="literal">size</code> option. Setting this to a value higher than the <code class="literal">size</code> can be
useful in order to get a more accurate document frequency for spelling
corrections at the cost of performance. Due to the fact that terms are
partitioned amongst shards, the shard level document frequencies of
spelling corrections may not be precise. Increasing this will make these
document frequencies more precise.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">max_inspections</code>
</p>
</td>
<td valign="top">
<p>
A factor that is used to multiply with the
<code class="literal">shards_size</code> in order to inspect more candidate spelling corrections on
the shard level. Can improve accuracy at the cost of performance.
Defaults to 5.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">min_doc_freq</code>
</p>
</td>
<td valign="top">
<p>
The minimal threshold in number of documents a
suggestion should appear in. This can be specified as an absolute number
or as a relative percentage of number of documents. This can improve
quality by only suggesting high frequency terms. Defaults to 0f and is
not enabled. If a value higher than 1 is specified, then the number
cannot be fractional. The shard level document frequencies are used for
this option.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">max_term_freq</code>
</p>
</td>
<td valign="top">
<p>
The maximum threshold in number of documents in which a
suggest text token can exist in order to be included. Can be a relative
percentage number (e.g., 0.4) or an absolute number to represent document
frequencies. If a value higher than 1 is specified, then fractional can
not be specified. Defaults to 0.01f. This can be used to exclude high
frequency terms — which are usually spelled correctly — from being spellchecked.
This also improves the spellcheck performance. The shard level document frequencies
are used for this option.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">string_distance</code>
</p>
</td>
<td valign="top">
<p>
</p>
<p>
Which string distance implementation to use for comparing how similar
suggested terms are. Five possible values can be specified:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">internal</code>: The default based on damerau_levenshtein but highly optimized
for comparing string distance for terms inside the index.
</li>
<li class="listitem">
<code class="literal">damerau_levenshtein</code>: String distance algorithm based on
Damerau-Levenshtein algorithm.
</li>
<li class="listitem">
<code class="literal">levenshtein</code>: String distance algorithm based on Levenshtein edit distance
algorithm.
</li>
<li class="listitem">
<code class="literal">jaro_winkler</code>: String distance algorithm based on Jaro-Winkler algorithm.
</li>
<li class="listitem">
<code class="literal">ngram</code>: String distance algorithm based on character n-grams.
</li>
</ul>
</div>

</td>
</tr>
</tbody>
</table>
</div>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="phrase-suggester"></a>Phrase Suggester<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/phrase-suggest.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>In order to understand the format of suggestions, please
read the <a class="xref" href="search-suggesters.html" title="Suggesters">Suggesters</a> page first.</p>
</div>
</div>
<p>The <code class="literal">term</code> suggester provides a very convenient API to access word
alternatives on a per token basis within a certain string distance. The API
allows accessing each token in the stream individually while
suggest-selection is left to the API consumer. Yet, often pre-selected
suggestions are required in order to present to the end-user. The
<code class="literal">phrase</code> suggester adds additional logic on top of the <code class="literal">term</code> suggester
to select entire corrected phrases instead of individual tokens weighted
based on <code class="literal">ngram-language</code> models. In practice this suggester will be
able to make better decisions about which tokens to pick based on
co-occurrence and frequencies.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_api_example"></a>API Example<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/phrase-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<p>In general the <code class="literal">phrase</code> suggester requires special mapping up front to work.
The <code class="literal">phrase</code> suggester examples on this page need the following mapping to
work. The <code class="literal">reverse</code> analyzer is used only in the last example.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT test
{
  "settings": {
    "index": {
      "number_of_shards": 1,
      "analysis": {
        "analyzer": {
          "trigram": {
            "type": "custom",
            "tokenizer": "standard",
            "filter": ["lowercase","shingle"]
          },
          "reverse": {
            "type": "custom",
            "tokenizer": "standard",
            "filter": ["lowercase","reverse"]
          }
        },
        "filter": {
          "shingle": {
            "type": "shingle",
            "min_shingle_size": 2,
            "max_shingle_size": 3
          }
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "fields": {
          "trigram": {
            "type": "text",
            "analyzer": "trigram"
          },
          "reverse": {
            "type": "text",
            "analyzer": "reverse"
          }
        }
      }
    }
  }
}
POST test/_doc?refresh=true
{"title": "noble warriors"}
POST test/_doc?refresh=true
{"title": "nobel prize"}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2005.console"></div>
<p>Once you have the analyzers and mappings set up you can use the <code class="literal">phrase</code>
suggester in the same spot you’d use the <code class="literal">term</code> suggester:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST test/_search
{
  "suggest": {
    "text": "noble prize",
    "simple_phrase": {
      "phrase": {
        "field": "title.trigram",
        "size": 1,
        "gram_size": 3,
        "direct_generator": [ {
          "field": "title.trigram",
          "suggest_mode": "always"
        } ],
        "highlight": {
          "pre_tag": "&lt;em&gt;",
          "post_tag": "&lt;/em&gt;"
        }
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2006.console"></div>
<p>The response contains suggestions scored by the most likely spelling correction first. In this case we received the expected correction "nobel prize".</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "_shards": ...
  "hits": ...
  "timed_out": false,
  "took": 3,
  "suggest": {
    "simple_phrase" : [
      {
        "text" : "noble prize",
        "offset" : 0,
        "length" : 11,
        "options" : [ {
          "text" : "nobel prize",
          "highlighted": "&lt;em&gt;nobel&lt;/em&gt; prize",
          "score" : 0.48614594
        }]
      }
    ]
  }
}</pre>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_basic_phrase_suggest_api_parameters"></a>Basic Phrase suggest API parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/phrase-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">field</code>
</p>
</td>
<td valign="top">
<p>
The name of the field used to do n-gram lookups for the
language model, the suggester will use this field to gain statistics to
score corrections. This field is mandatory.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">gram_size</code>
</p>
</td>
<td valign="top">
<p>
Sets max size of the n-grams (shingles) in the <code class="literal">field</code>.
If the field doesn’t contain n-grams (shingles), this should be omitted
or set to <code class="literal">1</code>. Note that Elasticsearch tries to detect the gram size
based on the specified <code class="literal">field</code>. If the field uses a <code class="literal">shingle</code> filter, the
<code class="literal">gram_size</code> is set to the <code class="literal">max_shingle_size</code> if not explicitly set.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">real_word_error_likelihood</code>
</p>
</td>
<td valign="top">
<p>
The likelihood of a term being a
misspelled even if the term exists in the dictionary. The default is
<code class="literal">0.95</code>, meaning 5% of the real words are misspelled.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">confidence</code>
</p>
</td>
<td valign="top">
<p>
The confidence level defines a factor applied to the
input phrases score which is used as a threshold for other suggest
candidates. Only candidates that score higher than the threshold will be
included in the result. For instance a confidence level of <code class="literal">1.0</code> will
only return suggestions that score higher than the input phrase. If set
to <code class="literal">0.0</code> the top N candidates are returned. The default is <code class="literal">1.0</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">max_errors</code>
</p>
</td>
<td valign="top">
<p>
The maximum percentage of the terms
considered to be misspellings in order to form a correction. This method
accepts a float value in the range <code class="literal">[0..1)</code> as a fraction of the actual
query terms or a number <code class="literal">&gt;=1</code> as an absolute number of query terms. The
default is set to <code class="literal">1.0</code>, meaning only corrections with
at most one misspelled term are returned.  Note that setting this too high
can negatively impact performance. Low values like <code class="literal">1</code> or <code class="literal">2</code> are recommended;
otherwise the time spend in suggest calls might exceed the time spend in
query execution.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">separator</code>
</p>
</td>
<td valign="top">
<p>
The separator that is used to separate terms in the
bigram field. If not set the whitespace character is used as a
separator.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">size</code>
</p>
</td>
<td valign="top">
<p>
The number of candidates that are generated for each
individual query term. Low numbers like <code class="literal">3</code> or <code class="literal">5</code> typically produce good
results. Raising this can bring up terms with higher edit distances. The
default is <code class="literal">5</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">analyzer</code>
</p>
</td>
<td valign="top">
<p>
Sets the analyzer to analyze to suggest text with.
Defaults to the search analyzer of the suggest field passed via <code class="literal">field</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">shard_size</code>
</p>
</td>
<td valign="top">
<p>
Sets the maximum number of suggested terms to be
retrieved from each individual shard. During the reduce phase, only the
top N suggestions are returned based on the <code class="literal">size</code> option. Defaults to
<code class="literal">5</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">text</code>
</p>
</td>
<td valign="top">
<p>
Sets the text / query to provide suggestions for.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">highlight</code>
</p>
</td>
<td valign="top">
<p>
Sets up suggestion highlighting.  If not provided then
no <code class="literal">highlighted</code> field is returned.  If provided must
contain exactly <code class="literal">pre_tag</code> and <code class="literal">post_tag</code>, which are
wrapped around the changed tokens.  If multiple tokens
in a row are changed the entire phrase of changed tokens
is wrapped rather than each token.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">collate</code>
</p>
</td>
<td valign="top">
<p>
Checks each suggestion against the specified <code class="literal">query</code> to prune suggestions
for which no matching docs exist in the index. The collate query for a
suggestion is run only on the local shard from which the suggestion has
been generated from. The <code class="literal">query</code> must be specified and it can be templated,
see <a class="xref" href="search-template.html" title="Search Template">search templates</a> for more information.
The current suggestion is automatically made available as the <code class="literal">{{suggestion}}</code>
variable, which should be used in your query.  You can still specify
your own template <code class="literal">params</code> — the <code class="literal">suggestion</code> value will be added to the
variables you specify. Additionally, you can specify a <code class="literal">prune</code> to control
if all phrase suggestions will be returned; when set to <code class="literal">true</code> the suggestions
will have an additional option <code class="literal">collate_match</code>, which will be <code class="literal">true</code> if
matching documents for the phrase was found, <code class="literal">false</code> otherwise.
The default value for <code class="literal">prune</code> is <code class="literal">false</code>.
</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST test/_search
{
  "suggest": {
    "text" : "noble prize",
    "simple_phrase" : {
      "phrase" : {
        "field" :  "title.trigram",
        "size" :   1,
        "direct_generator" : [ {
          "field" :            "title.trigram",
          "suggest_mode" :     "always",
          "min_word_length" :  1
        } ],
        "collate": {
          "query": { <a id="CO627-1"></a><i class="conum" data-value="1"></i>
            "source" : {
              "match": {
                "{{field_name}}" : "{{suggestion}}" <a id="CO627-2"></a><i class="conum" data-value="2"></i>
              }
            }
          },
          "params": {"field_name" : "title"}, <a id="CO627-3"></a><i class="conum" data-value="3"></i>
          "prune": true <a id="CO627-4"></a><i class="conum" data-value="4"></i>
        }
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2007.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO627-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>This query will be run once for every suggestion.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO627-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>The <code class="literal">{{suggestion}}</code> variable will be replaced by the text
of each suggestion.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO627-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>An additional <code class="literal">field_name</code> variable has been specified in
<code class="literal">params</code> and is used by the <code class="literal">match</code> query.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO627-4"><i class="conum" data-value="4"></i></a></p>
</td>
<td align="left" valign="top">
<p>All suggestions will be returned with an extra <code class="literal">collate_match</code>
option indicating whether the generated phrase matched any
document.</p>
</td>
</tr>
</table>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_smoothing_models"></a>Smoothing Models<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/phrase-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The <code class="literal">phrase</code> suggester supports multiple smoothing models to balance
weight between infrequent grams (grams (shingles) are not existing in
the index) and frequent grams (appear at least once in the index). The
smoothing model can be selected by setting the <code class="literal">smoothing</code> parameter
to one of the following options. Each smoothing model supports specific
properties that can be configured.</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">stupid_backoff</code>
</p>
</td>
<td valign="top">
<p>
A simple backoff model that backs off to lower
order n-gram models if the higher order count is <code class="literal">0</code> and discounts the
lower order n-gram model by a constant factor. The default <code class="literal">discount</code> is
<code class="literal">0.4</code>. Stupid Backoff is the default model.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">laplace</code>
</p>
</td>
<td valign="top">
<p>
A smoothing model that uses an additive smoothing where a
constant (typically <code class="literal">1.0</code> or smaller) is added to all counts to balance
weights. The default <code class="literal">alpha</code> is <code class="literal">0.5</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">linear_interpolation</code>
</p>
</td>
<td valign="top">
<p>
A smoothing model that takes the weighted
mean of the unigrams, bigrams, and trigrams based on user supplied
weights (lambdas). Linear Interpolation doesn’t have any default values.
All parameters (<code class="literal">trigram_lambda</code>, <code class="literal">bigram_lambda</code>, <code class="literal">unigram_lambda</code>)
must be supplied.
</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST test/_search
{
  "suggest": {
    "text" : "obel prize",
    "simple_phrase" : {
      "phrase" : {
        "field" : "title.trigram",
        "size" : 1,
        "smoothing" : {
          "laplace" : {
            "alpha" : 0.7
          }
        }
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2008.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_candidate_generators"></a>Candidate Generators<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/phrase-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The <code class="literal">phrase</code> suggester uses candidate generators to produce a list of
possible terms per term in the given text. A single candidate generator
is similar to a <code class="literal">term</code> suggester called for each individual term in the
text. The output of the generators is subsequently scored in combination
with the candidates from the other terms for suggestion candidates.</p>
<p>Currently only one type of candidate generator is supported, the
<code class="literal">direct_generator</code>. The Phrase suggest API accepts a list of generators
under the key <code class="literal">direct_generator</code>; each of the generators in the list is
called per term in the original text.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_direct_generators"></a>Direct Generators<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/phrase-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The direct generators support the following parameters:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">field</code>
</p>
</td>
<td valign="top">
<p>
The field to fetch the candidate suggestions from. This is
a required option that either needs to be set globally or per
suggestion.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">size</code>
</p>
</td>
<td valign="top">
<p>
The maximum corrections to be returned per suggest text token.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">suggest_mode</code>
</p>
</td>
<td valign="top">
<p>
</p>
<p>
The suggest mode controls what suggestions are included on the suggestions
generated on each shard. All values other than <code class="literal">always</code> can be thought of
as an optimization to generate fewer suggestions to test on each shard and
are not rechecked when combining the suggestions generated on each
shard. Thus <code class="literal">missing</code> will generate suggestions for terms on shards that do
not contain them even if other shards do contain them. Those should be
filtered out using <code class="literal">confidence</code>. Three possible values can be specified:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">missing</code>: Only generate suggestions for terms that are not in the
shard. This is the default.
</li>
<li class="listitem">
<code class="literal">popular</code>: Only suggest terms that occur in more docs on the shard than
the original term.
</li>
<li class="listitem">
<code class="literal">always</code>: Suggest any matching suggestions based on terms in the
suggest text.
</li>
</ul>
</div>

</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">max_edits</code>
</p>
</td>
<td valign="top">
<p>
The maximum edit distance candidate suggestions can have
in order to be considered as a suggestion. Can only be a value between 1
and 2. Any other value results in a bad request error being thrown.
Defaults to 2.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">prefix_length</code>
</p>
</td>
<td valign="top">
<p>
The number of minimal prefix characters that must
match in order be a candidate suggestions. Defaults to 1. Increasing
this number improves spellcheck performance. Usually misspellings don’t
occur in the beginning of terms. (Old name "prefix_len" is deprecated)
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">min_word_length</code>
</p>
</td>
<td valign="top">
<p>
The minimum length a suggest text term must have in
order to be included. Defaults to 4. (Old name "min_word_len" is deprecated)
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">max_inspections</code>
</p>
</td>
<td valign="top">
<p>
A factor that is used to multiply with the
<code class="literal">shards_size</code> in order to inspect more candidate spelling corrections on
the shard level. Can improve accuracy at the cost of performance.
Defaults to 5.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">min_doc_freq</code>
</p>
</td>
<td valign="top">
<p>
The minimal threshold in number of documents a
suggestion should appear in. This can be specified as an absolute number
or as a relative percentage of number of documents. This can improve
quality by only suggesting high frequency terms. Defaults to 0f and is
not enabled. If a value higher than 1 is specified, then the number
cannot be fractional. The shard level document frequencies are used for
this option.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">max_term_freq</code>
</p>
</td>
<td valign="top">
<p>
The maximum threshold in number of documents in which a
suggest text token can exist in order to be included. Can be a relative
percentage number (e.g., 0.4) or an absolute number to represent document
frequencies. If a value higher than 1 is specified, then fractional can
not be specified. Defaults to 0.01f. This can be used to exclude high
frequency terms — which are usually spelled correctly — from being spellchecked. This also improves the spellcheck
performance. The shard level document frequencies are used for this
option.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">pre_filter</code>
</p>
</td>
<td valign="top">
<p>
A filter (analyzer) that is applied to each of the
tokens passed to this candidate generator. This filter is applied to the
original token before candidates are generated.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">post_filter</code>
</p>
</td>
<td valign="top">
<p>
A filter (analyzer) that is applied to each of the
generated tokens before they are passed to the actual phrase scorer.
</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>The following example shows a <code class="literal">phrase</code> suggest call with two generators:
the first one is using a field containing ordinary indexed terms, and the
second one uses a field that uses terms indexed with a <code class="literal">reverse</code> filter
(tokens are index in reverse order). This is used to overcome the limitation
of the direct generators to require a constant prefix to provide
high-performance suggestions. The <code class="literal">pre_filter</code> and <code class="literal">post_filter</code> options
accept ordinary analyzer names.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST test/_search
{
  "suggest": {
    "text" : "obel prize",
    "simple_phrase" : {
      "phrase" : {
        "field" : "title.trigram",
        "size" : 1,
        "direct_generator" : [ {
          "field" : "title.trigram",
          "suggest_mode" : "always"
        }, {
          "field" : "title.reverse",
          "suggest_mode" : "always",
          "pre_filter" : "reverse",
          "post_filter" : "reverse"
        } ]
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2009.console"></div>
<p><code class="literal">pre_filter</code> and <code class="literal">post_filter</code> can also be used to inject synonyms after
candidates are generated. For instance for the query <code class="literal">captain usq</code> we
might generate a candidate <code class="literal">usa</code> for the term <code class="literal">usq</code>, which is a synonym for
<code class="literal">america</code>. This allows us to present <code class="literal">captain america</code> to the user if this
phrase scores high enough.</p>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="completion-suggester"></a>Completion Suggester<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/completion-suggest.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>In order to understand the format of suggestions, please
read the <a class="xref" href="search-suggesters.html" title="Suggesters">Suggesters</a> page first. For more flexible
search-as-you-type searches that do not use suggesters, see the
<a class="xref" href="search-as-you-type.html" title="Search-as-you-type datatype"><code class="literal">search_as_you_type</code> field type</a>.</p>
</div>
</div>
<p>The <code class="literal">completion</code> suggester provides auto-complete/search-as-you-type
functionality. This is a navigational feature to guide users to
relevant results as they are typing, improving search precision.
It is not meant for spell correction or did-you-mean functionality
like the <code class="literal">term</code> or <code class="literal">phrase</code> suggesters.</p>
<p>Ideally, auto-complete functionality should be as fast as a user
types to provide instant feedback relevant to what a user has already
typed in. Hence, <code class="literal">completion</code> suggester is optimized for speed.
The suggester uses data structures that enable fast lookups,
but are costly to build and are stored in-memory.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="completion-suggester-mapping"></a>Mapping<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/completion-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<p>To use this feature, specify a special mapping for this field,
which indexes the field values for fast completions.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT music
{
    "mappings": {
        "properties" : {
            "suggest" : {
                "type" : "completion"
            },
            "title" : {
                "type": "keyword"
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2010.console"></div>
<p>Mapping supports the following parameters:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">analyzer</code>
</p>
</td>
<td valign="top">
<p>
The index analyzer to use, defaults to <code class="literal">simple</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">search_analyzer</code>
</p>
</td>
<td valign="top">
<p>
The search analyzer to use, defaults to value of <code class="literal">analyzer</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">preserve_separators</code>
</p>
</td>
<td valign="top">
<p>
Preserves the separators, defaults to <code class="literal">true</code>.
If disabled, you could find a field starting with <code class="literal">Foo Fighters</code>, if you
suggest for <code class="literal">foof</code>.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">preserve_position_increments</code>
</p>
</td>
<td valign="top">
<p>
Enables position increments, defaults to <code class="literal">true</code>.
If disabled and using stopwords analyzer, you could get a
field starting with <code class="literal">The Beatles</code>, if you suggest for <code class="literal">b</code>. <span class="strong strong"><strong>Note</strong></span>: You
could also achieve this by indexing two inputs, <code class="literal">Beatles</code> and
<code class="literal">The Beatles</code>, no need to change a simple analyzer, if you are able to
enrich your data.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">max_input_length</code>
</p>
</td>
<td valign="top">
<p>
Limits the length of a single input, defaults to <code class="literal">50</code> UTF-16 code points.
This limit is only used at index time to reduce the total number of
characters per input string in order to prevent massive inputs from
bloating the underlying datastructure. Most use cases won’t be influenced
by the default value since prefix completions seldom grow beyond prefixes longer
than a handful of characters.
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="indexing"></a>Indexing<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/completion-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<p>You index suggestions like any other field. A suggestion is made of an
<code class="literal">input</code> and an optional <code class="literal">weight</code> attribute. An <code class="literal">input</code> is the expected
text to be matched by a suggestion query and the <code class="literal">weight</code> determines how
the suggestions will be scored. Indexing a suggestion is as follows:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT music/_doc/1?refresh
{
    "suggest" : {
        "input": [ "Nevermind", "Nirvana" ],
        "weight" : 34
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2011.console"></div>
<p>The following parameters are supported:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">input</code>
</p>
</td>
<td valign="top">
<p>
</p>
<p>
The input to store, this can be an array of strings or just
a string. This field is mandatory.
</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>This value cannot contain the following UTF-16 control characters:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">\u0000</code> (null)
</li>
<li class="listitem">
<code class="literal">\u001f</code> (information separator one)
</li>
<li class="listitem">
<code class="literal">\u001e</code> (information separator two)
</li>
</ul>
</div>
</div>
</div>

</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">weight</code>
</p>
</td>
<td valign="top">
<p>
A positive integer or a string containing a positive integer,
which defines a weight and allows you to rank your suggestions.
This field is optional.
</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>You can index multiple suggestions for a document as follows:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT music/_doc/1?refresh
{
    "suggest" : [
        {
            "input": "Nevermind",
            "weight" : 10
        },
        {
            "input": "Nirvana",
            "weight" : 3
        }
    ]
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2012.console"></div>
<p>You can use the following shorthand form. Note that you can not specify
a weight with suggestion(s) in the shorthand form.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT music/_doc/1?refresh
{
  "suggest" : [ "Nevermind", "Nirvana" ]
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2013.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="querying"></a>Querying<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/completion-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Suggesting works as usual, except that you have to specify the suggest
type as <code class="literal">completion</code>. Suggestions are near real-time, which means
new suggestions can be made visible by <a class="xref" href="indices-refresh.html" title="Refresh API">refresh</a> and
documents once deleted are never shown. This request:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST music/_search?pretty
{
    "suggest": {
        "song-suggest" : {
            "prefix" : "nir", <a id="CO628-1"></a><i class="conum" data-value="1"></i>
            "completion" : { <a id="CO628-2"></a><i class="conum" data-value="2"></i>
                "field" : "suggest" <a id="CO628-3"></a><i class="conum" data-value="3"></i>
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2014.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO628-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Prefix used to search for suggestions</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO628-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Type of suggestions</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO628-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>Name of the field to search for suggestions in</p>
</td>
</tr>
</table>
</div>
<p>returns this response:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits": ...
  "took": 2,
  "timed_out": false,
  "suggest": {
    "song-suggest" : [ {
      "text" : "nir",
      "offset" : 0,
      "length" : 3,
      "options" : [ {
        "text" : "Nirvana",
        "_index": "music",
        "_type": "_doc",
        "_id": "1",
        "_score": 1.0,
        "_source": {
          "suggest": ["Nevermind", "Nirvana"]
        }
      } ]
    } ]
  }
}</pre>
</div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p><code class="literal">_source</code> meta-field must be enabled, which is the default
behavior, to enable returning <code class="literal">_source</code> with suggestions.</p>
</div>
</div>
<p>The configured weight for a suggestion is returned as <code class="literal">_score</code>. The
<code class="literal">text</code> field uses the <code class="literal">input</code> of your indexed suggestion. Suggestions
return the full document <code class="literal">_source</code> by default. The size of the <code class="literal">_source</code>
can impact performance due to disk fetch and network transport overhead.
To save some network overhead, filter out unnecessary fields from the <code class="literal">_source</code>
using <a class="xref" href="run-a-search.html#source-filtering" title="Source filtering">source filtering</a> to minimize
<code class="literal">_source</code> size. Note that the _suggest endpoint doesn’t support source
filtering but using suggest on the <code class="literal">_search</code> endpoint does:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST music/_search
{
    "_source": "suggest", <a id="CO629-1"></a><i class="conum" data-value="1"></i>
    "suggest": {
        "song-suggest" : {
            "prefix" : "nir",
            "completion" : {
                "field" : "suggest", <a id="CO629-2"></a><i class="conum" data-value="2"></i>
                "size" : 5 <a id="CO629-3"></a><i class="conum" data-value="3"></i>
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2015.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO629-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Filter the source to return only the <code class="literal">suggest</code> field</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO629-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Name of the field to search for suggestions in</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO629-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>Number of suggestions to return</p>
</td>
</tr>
</table>
</div>
<p>Which should look like:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
    "took": 6,
    "timed_out": false,
    "_shards" : {
        "total" : 1,
        "successful" : 1,
        "skipped" : 0,
        "failed" : 0
    },
    "hits": {
        "total" : {
            "value": 0,
            "relation": "eq"
        },
        "max_score" : null,
        "hits" : []
    },
    "suggest": {
        "song-suggest" : [ {
            "text" : "nir",
            "offset" : 0,
            "length" : 3,
            "options" : [ {
                "text" : "Nirvana",
                "_index": "music",
                "_type": "_doc",
                "_id": "1",
                "_score": 1.0,
                "_source": {
                    "suggest": ["Nevermind", "Nirvana"]
                }
            } ]
        } ]
    }
}</pre>
</div>
<p>The basic completion suggester query supports the following parameters:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">field</code>
</p>
</td>
<td valign="top">
<p>
The name of the field on which to run the query (required).
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">size</code>
</p>
</td>
<td valign="top">
<p>
The number of suggestions to return (defaults to <code class="literal">5</code>).
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">skip_duplicates</code>
</p>
</td>
<td valign="top">
<p>
Whether duplicate suggestions should be filtered out (defaults to <code class="literal">false</code>).
</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The completion suggester considers all documents in the index.
See <a class="xref" href="search-suggesters.html#context-suggester" title="Context Suggester">Context Suggester</a> for an explanation of how to query a subset of
documents instead.</p>
</div>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>In case of completion queries spanning more than one shard, the suggest
is executed in two phases, where the last phase fetches the relevant documents
from shards, implying executing completion requests against a single shard is
more performant due to the document fetch overhead when the suggest spans
multiple shards. To get best performance for completions, it is recommended to
index completions into a single shard index. In case of high heap usage due to
shard size, it is still recommended to break index into multiple shards instead
of optimizing for completion performance.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="skip_duplicates"></a>Skip duplicate suggestions<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/completion-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Queries can return duplicate suggestions coming from different documents.
It is possible to modify this behavior by setting <code class="literal">skip_duplicates</code> to true.
When set, this option filters out documents with duplicate suggestions from the result.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST music/_search?pretty
{
    "suggest": {
        "song-suggest" : {
            "prefix" : "nor",
            "completion" : {
                "field" : "suggest",
                "skip_duplicates": true
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2016.console"></div>
<div class="warning admon">
<div class="icon"></div>
<div class="admon_content">
<p>When set to true, this option can slow down search because more suggestions
need to be visited to find the top N.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="fuzzy"></a>Fuzzy queries<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/completion-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The completion suggester also supports fuzzy queries — this means
you can have a typo in your search and still get results back.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST music/_search?pretty
{
    "suggest": {
        "song-suggest" : {
            "prefix" : "nor",
            "completion" : {
                "field" : "suggest",
                "fuzzy" : {
                    "fuzziness" : 2
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2017.console"></div>
<p>Suggestions that share the longest prefix to the query <code class="literal">prefix</code> will
be scored higher.</p>
<p>The fuzzy query can take specific fuzzy parameters.
The following parameters are supported:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">fuzziness</code>
</p>
</td>
<td valign="top">
<p>
The fuzziness factor, defaults to <code class="literal">AUTO</code>.
See  <a class="xref" href="common-options.html#fuzziness" title="Fuzziness">Fuzziness</a> for allowed settings.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">transpositions</code>
</p>
</td>
<td valign="top">
<p>
if set to <code class="literal">true</code>, transpositions are counted
as one change instead of two, defaults to <code class="literal">true</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">min_length</code>
</p>
</td>
<td valign="top">
<p>
Minimum length of the input before fuzzy
suggestions are returned, defaults <code class="literal">3</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">prefix_length</code>
</p>
</td>
<td valign="top">
<p>
Minimum length of the input, which is not
checked for fuzzy alternatives, defaults to <code class="literal">1</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">unicode_aware</code>
</p>
</td>
<td valign="top">
<p>
If <code class="literal">true</code>, all measurements (like fuzzy edit
distance, transpositions, and lengths) are
measured in Unicode code points instead of
in bytes.  This is slightly slower than raw
bytes, so it is set to <code class="literal">false</code> by default.
</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If you want to stick with the default values, but
      still use fuzzy, you can either use <code class="literal">fuzzy: {}</code>
      or <code class="literal">fuzzy: true</code>.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="regex"></a>Regex queries<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/completion-suggest.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The completion suggester also supports regex queries meaning
you can express a prefix as a regular expression</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST music/_search?pretty
{
    "suggest": {
        "song-suggest" : {
            "regex" : "n[ever|i]r",
            "completion" : {
                "field" : "suggest"
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2018.console"></div>
<p>The regex query can take specific regex parameters.
The following parameters are supported:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">flags</code>
</p>
</td>
<td valign="top">
<p>
Possible flags are <code class="literal">ALL</code> (default), <code class="literal">ANYSTRING</code>, <code class="literal">COMPLEMENT</code>,
<code class="literal">EMPTY</code>, <code class="literal">INTERSECTION</code>, <code class="literal">INTERVAL</code>, or <code class="literal">NONE</code>. See <a class="xref" href="query-dsl-regexp-query.html" title="Regexp query">regexp-syntax</a>
for their meaning
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">max_determinized_states</code>
</p>
</td>
<td valign="top">
<p>
Regular expressions are dangerous because it’s easy to accidentally
create an innocuous looking one that requires an exponential number of
internal determinized automaton states (and corresponding RAM and CPU)
for Lucene to execute.  Lucene prevents these using the
<code class="literal">max_determinized_states</code> setting (defaults to 10000).  You can raise
this limit to allow more complex regular expressions to execute.
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="context-suggester"></a>Context Suggester<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/context-suggest.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The completion suggester considers all documents in the index, but it is often
desirable to serve suggestions filtered and/or boosted by some criteria.
For example, you want to suggest song titles filtered by certain artists or
you want to boost song titles based on their genre.</p>
<p>To achieve suggestion filtering and/or boosting, you can add context mappings while
configuring a completion field. You can define multiple context mappings for a
completion field.
Every context mapping has a unique name and a type. There are two types: <code class="literal">category</code>
and <code class="literal">geo</code>. Context mappings are configured under the <code class="literal">contexts</code> parameter in
the field mapping.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>It is mandatory to provide a context when indexing and querying
      a context enabled completion field.</p>
</div>
</div>
<p>The following defines types, each with two context mappings for a completion
field:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT place
{
    "mappings": {
        "properties" : {
            "suggest" : {
                "type" : "completion",
                "contexts": [
                    { <a id="CO630-1"></a><i class="conum" data-value="1"></i>
                        "name": "place_type",
                        "type": "category"
                    },
                    { <a id="CO630-2"></a><i class="conum" data-value="2"></i>
                        "name": "location",
                        "type": "geo",
                        "precision": 4
                    }
                ]
            }
        }
    }
}
PUT place_path_category
{
    "mappings": {
        "properties" : {
            "suggest" : {
                "type" : "completion",
                "contexts": [
                    { <a id="CO630-3"></a><i class="conum" data-value="3"></i>
                        "name": "place_type",
                        "type": "category",
                        "path": "cat"
                    },
                    { <a id="CO630-4"></a><i class="conum" data-value="4"></i>
                        "name": "location",
                        "type": "geo",
                        "precision": 4,
                        "path": "loc"
                    }
                ]
            },
            "loc": {
                "type": "geo_point"
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2019.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO630-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Defines a <code class="literal">category</code> context named <em>place_type</em> where the categories must be
sent with the suggestions.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO630-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Defines a <code class="literal">geo</code> context named <em>location</em> where the categories must be sent
with the suggestions.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO630-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>Defines a <code class="literal">category</code> context named <em>place_type</em> where the categories are
read from the <code class="literal">cat</code> field.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO630-4"><i class="conum" data-value="4"></i></a></p>
</td>
<td align="left" valign="top">
<p>Defines a <code class="literal">geo</code> context named <em>location</em> where the categories are read from
the <code class="literal">loc</code> field.</p>
</td>
</tr>
</table>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Adding context mappings increases the index size for completion field. The completion index
is entirely heap resident, you can monitor the completion field index size using <a class="xref" href="indices-stats.html" title="Index stats API">Index stats</a>.</p>
</div>
</div>
<h5>
<a id="suggester-context-category"></a>Category Context<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/context-suggest.asciidoc">edit</a>
</h5>
<p>The <code class="literal">category</code> context allows you to associate one or more categories with suggestions at index
time. At query time, suggestions can be filtered and boosted by their associated categories.</p>
<p>The mappings are set up like the <code class="literal">place_type</code> fields above. If <code class="literal">path</code> is defined
then the categories are read from that path in the document, otherwise they must
be sent in the suggest field like this:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT place/_doc/1
{
    "suggest": {
        "input": ["timmy's", "starbucks", "dunkin donuts"],
        "contexts": {
            "place_type": ["cafe", "food"] <a id="CO631-1"></a><i class="conum" data-value="1"></i>
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2020.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO631-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>These suggestions will be associated with <em>cafe</em> and <em>food</em> category.</p>
</td>
</tr>
</table>
</div>
<p>If the mapping had a <code class="literal">path</code> then the following index request would be enough to
add the categories:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT place_path_category/_doc/1
{
    "suggest": ["timmy's", "starbucks", "dunkin donuts"],
    "cat": ["cafe", "food"] <a id="CO632-1"></a><i class="conum" data-value="1"></i>
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2021.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO632-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>These suggestions will be associated with <em>cafe</em> and <em>food</em> category.</p>
</td>
</tr>
</table>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If context mapping references another field and the categories
are explicitly indexed, the suggestions are indexed with both set
of categories.</p>
</div>
</div>
<h6>
<a id="_category_query"></a>Category Query<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/context-suggest.asciidoc">edit</a>
</h6>
<p>Suggestions can be filtered by one or more categories. The following
filters suggestions by multiple categories:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST place/_search?pretty
{
    "suggest": {
        "place_suggestion" : {
            "prefix" : "tim",
            "completion" : {
                "field" : "suggest",
                "size": 10,
                "contexts": {
                    "place_type": [ "cafe", "restaurants" ]
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2022.console"></div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If multiple categories or category contexts are set on the query
they are merged as a disjunction. This means that suggestions match
if they contain at least one of the provided context values.</p>
</div>
</div>
<p>Suggestions with certain categories can be boosted higher than others.
The following filters suggestions by categories and additionally boosts
suggestions associated with some categories:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST place/_search?pretty
{
    "suggest": {
        "place_suggestion" : {
            "prefix" : "tim",
            "completion" : {
                "field" : "suggest",
                "size": 10,
                "contexts": {
                    "place_type": [ <a id="CO633-1"></a><i class="conum" data-value="1"></i>
                        { "context" : "cafe" },
                        { "context" : "restaurants", "boost": 2 }
                     ]
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2023.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO633-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The context query filter suggestions associated with
categories <em>cafe</em> and <em>restaurants</em> and boosts the
suggestions associated with <em>restaurants</em> by a
factor of <code class="literal">2</code></p>
</td>
</tr>
</table>
</div>
<p>In addition to accepting category values, a context query can be composed of
multiple category context clauses. The following parameters are supported for a
<code class="literal">category</code> context clause:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">context</code>
</p>
</td>
<td valign="top">
<p>
The value of the category to filter/boost on.
This is mandatory.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">boost</code>
</p>
</td>
<td valign="top">
<p>
The factor by which the score of the suggestion
should be boosted, the score is computed by
multiplying the boost with the suggestion weight,
defaults to <code class="literal">1</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">prefix</code>
</p>
</td>
<td valign="top">
<p>
Whether the category value should be treated as a
prefix or not. For example, if set to <code class="literal">true</code>,
you can filter category of <em>type1</em>, <em>type2</em> and
so on, by specifying a category prefix of <em>type</em>.
Defaults to <code class="literal">false</code>
</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If a suggestion entry matches multiple contexts the final score is computed as the
maximum score produced by any matching contexts.</p>
</div>
</div>
<h5>
<a id="suggester-context-geo"></a>Geo location Context<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/context-suggest.asciidoc">edit</a>
</h5>
<p>A <code class="literal">geo</code> context allows you to associate one or more geo points or geohashes with suggestions
at index time. At query time, suggestions can be filtered and boosted if they are within
a certain distance of a specified geo location.</p>
<p>Internally, geo points are encoded as geohashes with the specified precision.</p>
<h6>
<a id="_geo_mapping"></a>Geo Mapping<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/context-suggest.asciidoc">edit</a>
</h6>
<p>In addition to the <code class="literal">path</code> setting, <code class="literal">geo</code> context mapping accepts the following settings:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">precision</code>
</p>
</td>
<td valign="top">
<p>
This defines the precision of the geohash to be indexed and can be specified
as a distance value (<code class="literal">5m</code>, <code class="literal">10km</code> etc.), or as a raw geohash precision (<code class="literal">1</code>..<code class="literal">12</code>).
Defaults to a raw geohash precision value of <code class="literal">6</code>.
</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The index time <code class="literal">precision</code> setting sets the maximum geohash precision that
can be used at query time.</p>
</div>
</div>
<h6>
<a id="_indexing_geo_contexts"></a>Indexing geo contexts<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/context-suggest.asciidoc">edit</a>
</h6>
<p><code class="literal">geo</code> contexts can be explicitly set with suggestions or be indexed from a geo point field in the
document via the <code class="literal">path</code> parameter, similar to <code class="literal">category</code> contexts. Associating multiple geo location context
with a suggestion, will index the suggestion for every geo location. The following indexes a suggestion
with two geo location contexts:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT place/_doc/1
{
    "suggest": {
        "input": "timmy's",
        "contexts": {
            "location": [
                {
                    "lat": 43.6624803,
                    "lon": -79.3863353
                },
                {
                    "lat": 43.6624718,
                    "lon": -79.3873227
                }
            ]
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2024.console"></div>
<h6>
<a id="_geo_location_query"></a>Geo location Query<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/context-suggest.asciidoc">edit</a>
</h6>
<p>Suggestions can be filtered and boosted with respect to how close they are to one or
more geo points. The following filters suggestions that fall within the area represented by
the encoded geohash of a geo point:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST place/_search
{
    "suggest": {
        "place_suggestion" : {
            "prefix" : "tim",
            "completion" : {
                "field" : "suggest",
                "size": 10,
                "contexts": {
                    "location": {
                        "lat": 43.662,
                        "lon": -79.380
                    }
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2025.console"></div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>When a location with a lower precision at query time is specified, all suggestions
that fall within the area will be considered.</p>
</div>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If multiple categories or category contexts are set on the query
they are merged as a disjunction. This means that suggestions match
if they contain at least one of the provided context values.</p>
</div>
</div>
<p>Suggestions that are within an area represented by a geohash can also be boosted higher
than others, as shown by the following:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST place/_search?pretty
{
    "suggest": {
        "place_suggestion" : {
            "prefix" : "tim",
            "completion" : {
                "field" : "suggest",
                "size": 10,
                "contexts": {
                    "location": [ <a id="CO634-1"></a><i class="conum" data-value="1"></i>
                        {
                            "lat": 43.6624803,
                            "lon": -79.3863353,
                            "precision": 2
                        },
                        {
                            "context": {
                                "lat": 43.6624803,
                                "lon": -79.3863353
                            },
                            "boost": 2
                        }
                     ]
                }
            }
        }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2026.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO634-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The context query filters for suggestions that fall under
the geo location represented by a geohash of <em>(43.662, -79.380)</em>
with a precision of <em>2</em> and boosts suggestions
that fall under the geohash representation of <em>(43.6624803, -79.3863353)</em>
with a default precision of <em>6</em> by a factor of <code class="literal">2</code></p>
</td>
</tr>
</table>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If a suggestion entry matches multiple contexts the final score is computed as the
maximum score produced by any matching contexts.</p>
</div>
</div>
<p>In addition to accepting context values, a context query can be composed of
multiple context clauses. The following parameters are supported for a
<code class="literal">category</code> context clause:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">context</code>
</p>
</td>
<td valign="top">
<p>
A geo point object or a geo hash string to filter or
boost the suggestion by. This is mandatory.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">boost</code>
</p>
</td>
<td valign="top">
<p>
The factor by which the score of the suggestion
should be boosted, the score is computed by
multiplying the boost with the suggestion weight,
defaults to <code class="literal">1</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">precision</code>
</p>
</td>
<td valign="top">
<p>
The precision of the geohash to encode the query geo point.
This can be specified as a distance value (<code class="literal">5m</code>, <code class="literal">10km</code> etc.),
or as a raw geohash precision (<code class="literal">1</code>..<code class="literal">12</code>).
Defaults to index time precision level.
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">neighbours</code>
</p>
</td>
<td valign="top">
<p>
Accepts an array of precision values at which
neighbouring geohashes should be taken into account.
precision value can be a distance value (<code class="literal">5m</code>, <code class="literal">10km</code> etc.)
or a raw geohash precision (<code class="literal">1</code>..<code class="literal">12</code>). Defaults to
generating neighbours for index time precision level.
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="return-suggesters-type"></a>Returning the type of the suggester<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/suggesters/misc.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Sometimes you need to know the exact type of a suggester in order to parse its results. The <code class="literal">typed_keys</code> parameter
 can be used to change the suggester’s name in the response so that it will be prefixed by its type.</p>
<p>Considering the following example with two suggesters <code class="literal">term</code> and <code class="literal">phrase</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST _search?typed_keys
{
  "suggest": {
    "text" : "some test mssage",
    "my-first-suggester" : {
      "term" : {
        "field" : "message"
      }
    },
    "my-second-suggester" : {
      "phrase" : {
        "field" : "message"
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2027.console"></div>
<p>In the response, the suggester names will be changed to respectively <code class="literal">term#my-first-suggester</code> and
<code class="literal">phrase#my-second-suggester</code>, reflecting the types of each suggestion:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "suggest": {
    "term#my-first-suggester": [ <a id="CO635-1"></a><i class="conum" data-value="1"></i>
      {
        "text": "some",
        "offset": 0,
        "length": 4,
        "options": []
      },
      {
        "text": "test",
        "offset": 5,
        "length": 4,
        "options": []
      },
      {
        "text": "mssage",
        "offset": 10,
        "length": 6,
        "options": [
          {
            "text": "message",
            "score": 0.8333333,
            "freq": 4
          }
        ]
      }
    ],
    "phrase#my-second-suggester": [ <a id="CO635-2"></a><i class="conum" data-value="2"></i>
      {
        "text": "some test mssage",
        "offset": 0,
        "length": 16,
        "options": [
          {
            "text": "some test message",
            "score": 0.030227963
          }
        ]
      }
    ]
  },
  ...
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO635-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The name <code class="literal">my-first-suggester</code> now contains the <code class="literal">term</code> prefix.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO635-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>The name <code class="literal">my-second-suggester</code> now contains the <code class="literal">phrase</code> prefix.</p>
</td>
</tr>
</table>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="search-shards.html">« Search Shards API</a>
</span>
<span class="next">
<a href="search-multi-search.html">Multi Search API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>